跳到主要内容

状态机播放（State Machine Playback）

概览（Overview）​

State Machine（状态机）是 Rive 运行时交互的核心。

相比直接操纵线性动画，状态机更稳定、可维护性更高，推荐作为默认方案。

编辑器设计参考：

  • [State Machine（Editor）](/docs/Editor/State Machines/State%20Machine)

默认选择规则​

当你渲染一个 Artboard 时：

  1. 若显式指定 stateMachineName，优先使用它
  2. 否则使用该 artboard 的默认状态机
  3. 若无可用状态机，则可能表现为静态画面或仅线性动画（取决于内容）

播放语义（Playback Semantics）​

状态机会随每帧 advance 推进。

  • play：继续推进
  • pause：停止推进，停留在最后一帧
  • stop（某些 runtime 提供）：回到入口/初始状态
  • reset：重置状态

settle（静止优化）​

当运行时判断“没有后续变化”时，状态机会进入 settle（静止）并停止推进，以减少性能消耗。

触发外部变化（如数据绑定更新/用户输入）后会再次激活。

Web​

const r = new rive.Rive({
  src: 'https://cdn.rive.app/animations/vehicles.riv',
  stateMachines: 'bumpy',
  autoplay: true,
});

r.play();
r.pause();
r.stop();

React​

const { rive, RiveComponent } = useRive({
  src: 'https://cdn.rive.app/animations/vehicles.riv',
  stateMachines: 'bumpy',
  autoplay: true,
});

rive?.play();
rive?.pause();
rive?.stop();

React Native（新版）​

const { riveViewRef, setHybridRef } = useRive();

<RiveView
  file={riveFile}
  hybridRef={setHybridRef}
  autoPlay={false}
  artboardName="Truck"
  stateMachineName="bumpy"
/>

riveViewRef?.play();
riveViewRef?.pause();
riveViewRef?.reset();

Flutter​

推荐用 RiveWidgetController：

final controller = RiveWidgetController(
  riveFile,
  stateMachineSelector: StateMachineSelector.byName('State Machine 1'),
);

controller.active = true;  // 播放
controller.active = false; // 暂停

Apple（新版）​

常见流程：

let artboard = try await file.createArtboard("Artboard")
let sm = try await artboard.createStateMachine("StateMachine")
let rive = try await Rive(file: file, artboard: artboard, stateMachine: sm)

Android（Compose）​

val artboard = rememberArtboard(riveFile, "My Artboard")
val sm = rememberStateMachine(artboard, "My State Machine")

Rive(
  riveFile,
  artboard = artboard,
  stateMachine = sm,
  playing = true,
)

实践建议​

  1. 新项目优先 State Machine + Data Binding
  2. 避免把业务逻辑绑死在线性动画名称上
  3. 需要初始值注入时，可先 autoplay=false，设值后再 play
  4. 关注 settle 行为：属性变化后必要时触发 playIfNeeded（依 runtime）

相关文档​